package com.tbynet.jwp.repository.spi;

import com.tbynet.jwp.model.Posts;

import java.util.List;

/**
 * 文章缓存服务接口
 * 负责文章相关的缓存操作，包括文章详情、文章列表、搜索结果的缓存管理
 *
 * @ClassName: PostCacheService
 * @Description: 文章缓存服务，提供文章相关的缓存操作
 * @Author: 佰亿互联
 * @Date: 2025年11月4日
 *
 * @Copyright: 2025 www.tbynet.com Inc. All rights reserved.
 * 注意: 本内容仅限于内部传阅，禁止外泄以及用于其他的商业目
 */
public interface PostCacheService {

    // ============ 文章详情缓存方法 ============

    /**
     * 从缓存获取文章详情
     *
     * @param postId 文章ID
     * @return 文章对象，如果不存在返回null
     */
    Posts getPostFromCache(Object postId);

    /**
     * 将文章详情放入缓存
     *
     * @param post 文章对象
     */
    void putPostToCache(Posts post);

    /**
     * 从缓存移除文章详情
     *
     * @param postId 文章ID
     */
    void removePostFromCache(Object postId);

    // ============ 文章列表缓存方法 ============

    /**
     * 从缓存获取文章列表
     *
     * @param cacheKey 缓存键
     * @return 文章列表，如果不存在返回null
     */
    List<Posts> getPostListFromCache(String cacheKey);

    /**
     * 将文章列表放入缓存
     *
     * @param cacheKey 缓存键
     * @param posts 文章列表
     */
    void putPostListToCache(String cacheKey, List<Posts> posts);

    // ============ 文章计数缓存方法 ============

    /**
     * 从缓存获取文章总数
     *
     * @param countCacheKey 计数缓存键
     * @return 文章总数，如果不存在返回null
     */
    Long getPostCountFromCache(String countCacheKey);

    /**
     * 将文章总数放入缓存
     *
     * @param countCacheKey 计数缓存键
     * @param totalRow 总行数
     */
    void putPostCountToCache(String countCacheKey, long totalRow);

    /**
     * 从缓存移除文章计数
     *
     * @param countCacheKey 计数缓存键
     */
    void removePostCountFromCache(String countCacheKey);

    // ============ 文章统计缓存方法 ============

    /**
     * 从缓存获取文章统计信息
     *
     * @param statsKey 统计缓存键
     * @return 统计信息对象
     */
    Object getPostStatsFromCache(String statsKey);

    /**
     * 将文章统计信息放入缓存
     *
     * @param statsKey 统计缓存键
     * @param stats 统计信息对象
     */
    void putPostStatsToCache(String statsKey, Object stats);

    // ============ 缓存键生成方法 ============

    /**
     * 生成文章列表缓存键
     *
     * @param type 文章类型
     * @param status 文章状态
     * @param category 分类
     * @param tag 标签
     * @param page 页码
     * @param size 每页大小
     * @return 缓存键
     */
    String generateListCacheKey(String type, String status, String category, String tag, int page, int size);

    /**
     * 生成文章计数缓存键
     *
     * @param type 文章类型
     * @param status 文章状态
     * @param category 分类
     * @param tag 标签
     * @param keyword 关键词
     * @return 缓存键
     */
    String generateCountCacheKey(String type, String status, String category, String tag, String keyword);

    /**
     * 生成文章统计缓存键
     *
     * @param type 文章类型
     * @return 缓存键
     */
    String generateStatsCacheKey(String type);

    // ============ 搜索缓存方法 ============

    /**
     * 生成带搜索关键词的列表缓存键
     *
     * @param type 文章类型
     * @param status 文章状态
     * @param keyword 搜索关键词
     * @param category 分类
     * @param tag 标签
     * @param page 页码
     * @param size 每页大小
     * @return 缓存键
     */
    String generateSearchListCacheKey(String type, String status, String keyword,
                                      String category, String tag, int page, int size);

    /**
     * 生成带搜索关键词的计数缓存键
     *
     * @param type 文章类型
     * @param status 文章状态
     * @param keyword 搜索关键词
     * @param category 分类
     * @param tag 标签
     * @return 缓存键
     */
    String generateSearchCountCacheKey(String type, String status, String keyword,
                                       String category, String tag);

    /**
     * 生成高级搜索列表缓存键
     *
     * @param type 文章类型
     * @param status 文章状态
     * @param keyword 搜索关键词
     * @param category 分类
     * @param tag 标签
     * @param month 月份
     * @param sticky 是否置顶
     * @param page 页码
     * @param size 每页大小
     * @return 缓存键
     */
    String generateAdvancedSearchListCacheKey(String type, String status, String keyword,
                                              String category, String tag, String month,
                                              Boolean sticky, int page, int size);

    /**
     * 生成高级搜索计数缓存键
     *
     * @param type 文章类型
     * @param status 文章状态
     * @param keyword 搜索关键词
     * @param category 分类
     * @param tag 标签
     * @param month 月份
     * @param sticky 是否置顶
     * @return 缓存键
     */
    String generateAdvancedSearchCountCacheKey(String type, String status, String keyword,
                                               String category, String tag, String month,
                                               Boolean sticky);

    // ============ 缓存清除方法 ============

    /**
     * 清除所有文章缓存
     */
    void clearAllPostCache();

    /**
     * 清除搜索相关的缓存
     *
     * @param keyword 搜索关键词
     */
    void clearSearchCache(String keyword);

    /**
     * 清除所有高级搜索缓存
     */
    void clearAdvancedSearchCache();

    // ============ 批量缓存操作方法 ============

    /**
     * 批量获取文章缓存
     *
     * @param postIds 文章ID列表
     * @return 文章列表
     */
    List<Posts> batchGetPostsFromCache(List<Object> postIds);

    /**
     * 批量放入文章缓存
     *
     * @param posts 文章列表
     */
    void batchPutPostsToCache(List<Posts> posts);

    /**
     * 批量移除文章缓存
     *
     * @param postIds 文章ID列表
     */
    void batchRemovePostsFromCache(List<Object> postIds);
}